home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / focus.n < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. focus(n)                   Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      focus - Direct keyboard events to a particular window
  12.  
  13. SYNOPSIS
  14.      focus
  15.      focus _w_i_n_d_o_w
  16.      focus _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  17. _________________________________________________________________
  18.  
  19.  
  20. DESCRIPTION
  21.      The focus command is used to manage the Tk input focus.   At  |
  22.      any  given  time, one window in an application is designated  |
  23.      as the focus window for that application;  any key press  or  |
  24.      key release events directed to any window in the application  |
  25.      will be redirected instead to the focus window.  If there is  |
  26.      no  focus window for an application then keyboard events are  |
  27.      discarded.  Typically, windows that  are  prepared  to  deal  |
  28.      with  the focus (e.g. entries and other widgets that display  |
  29.      editable text) will claim the focus when mouse button  1  is  |
  30.      pressed  in  them.   When an application is created its main  |
  31.      window is initially given the focus.                          |
  32.  
  33.      The focus command can take any of the following forms:        |
  34.  
  35.      focus                                                              ||
  36.           If  invoked  with  no arguments, focus returns the path  |
  37.           name of the current focus window, or none if  there  is  |
  38.           no focus window.                                         |
  39.  
  40.      focus _w_i_n_d_o_w                                                       ||
  41.           If  invoked  with  a  single  argument  consisting of a  |
  42.           window's path name, focus sets the input focus to  that  |
  43.           window.  The return value is an empty string.            |
  44.  
  45.      focus default ?_w_i_n_d_o_w?                                             ||
  46.           If  _w_i_n_d_o_w  is  specified, it becomes the default focus  |
  47.           window (the window that receives the focus whenever the  |
  48.           focus  window  is  deleted)  and the command returns an  |
  49.           empty string.  If _w_i_n_d_o_w isn't specified,  the  command  |
  50.           returns the path name of the current default focus win-  |
  51.           dow, or none if there is no  default.   _W_i_n_d_o_w  may  be  |
  52.           specified  as  none  to  clear its existing value.  The  |
  53.           default window is initially none.                        |
  54.  
  55.      focus none                                                         ||
  56.           Clears the focus window, so that keyboard input to this  |
  57.           application will be discarded.                           |
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. focus(n)                   Tk Commands
  71.  
  72.  
  73.  
  74. FOCUS EVENTS                                                       |
  75.      Tk's model of the input focus is different than  X's  model,  |
  76.      and  the focus window set with the focus command is not usu-  |
  77.      ally the same as the X focus window.   Tk  never  explicitly  |
  78.      changes  the official X focus window.  It waits for the win-  |
  79.      dow manager to direct the X input  focus  to  and  from  the  |
  80.      application's  top-level  windows, and it intercepts FocusIn  |
  81.      and FocusOut events coming from the X server to detect these  |
  82.      changes.   All  of the focus events received from X are dis-  |
  83.      carded by Tk;  they never reach the  application.   Instead,  |
  84.      Tk  generates a different stream of FocusIn and FocusOut for  |
  85.      the application.  This means that FocusIn and  and  FocusOut  |
  86.      events seen by the application will not obey the conventions  |
  87.      described in the documentation for Xlib.                      |
  88.  
  89.      Tk applications receive two kinds of  FocusIn  and  FocusOut  |
  90.      events,  which  can be distinguished by their _d_e_t_a_i_l fields.  |
  91.      Events with a _d_e_t_a_i_l of NotifyAncestor are directed  to  the  |
  92.      current  focus window when it becomes active or inactive.  A  |
  93.      window is the  active  focus  whenever  two  conditions  are  |
  94.      simultaneously  true: (a) the window is the focus window for  |
  95.      its application, and (b) some top-level window in the appli-  |
  96.      cation  has received the X focus.  When this happens Tk gen-  |
  97.      erates a FocusIn event for  the  focus  window  with  detail  |
  98.      NotifyAncestor.   When  a  window  loses  the  active  focus  |
  99.      (either because the window manager removed  the  focus  from  |
  100.      the  application  or because the focus window changed within  |
  101.      the application) then it  receives  a  FocusOut  event  with  |
  102.      detail NotifyAncestor.                                        |
  103.  
  104.      The events described above are directed to the application's  |
  105.      focus window regardless of which top-level window within the  |
  106.      application has received the  focus.   The  second  kind  of  |
  107.      focus  event  is provided for applications that need to know  |
  108.      which particular top-level window has the X focus.  Tk  gen-  |
  109.      erates FocusIn and FocusOut events with detail NotifyVirtual  |
  110.      for top-level windows whenever they receive or  lose  the  X  |
  111.      focus.   These events are generated regardless of which win-  |
  112.      dow in the application has the Tk input focus.  They do  not  |
  113.      imply  that  keystrokes  will be directed to the window that  |
  114.      receives the event;  they simply  indicate  which  top-level  |
  115.      window  is active as far as the window manager is concerned.  |
  116.      If a top-level window is also the application's  focus  win-  |
  117.      dow,   then   it   will   receive   both  NotifyVirtual  and  |
  118.      NotifyAncestor events when it receives or loses the X focus.  |
  119.  
  120.      Tk does not generate the hierarchical chains of FocusIn  and  |
  121.      FocusOut events described in the Xlib documentation (e.g.  a  |
  122.      window can get a FocusIn or FocusOut event  without  all  of  |
  123.      its  ancestors  getting  events too).  Furthermore, the _m_o_d_e  |
  124.      field in focus events is always NotifyNormal  and  the  only  |
  125.      values  ever  present in the _d_e_t_a_i_l field are NotifyAncestor  |
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. focus(n)                   Tk Commands
  137.  
  138.  
  139.  
  140.      and NotifyVirtual.
  141.  
  142.  
  143. KEYWORDS
  144.      events, focus, keyboard, top-level, window manager
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.